QuickTime For Windows Programmers

Movies and Movie Files

QuickTime movies reside in movie files. On the Mac OS platform, such files carry the file type 'MooV' (defined in the QuickTime interface as a constant named MovieFileType ); on the Windows platform, they are identified by the file-name extension .mov .

Before reading a movie in from its movie file, you must first open the file with the QuickTime function OpenMovieFile :



 
OSErr

    OpenMovieFile

        (const FSSpec  *fileSpec,       // Identifies file to be opened

         short         *resRefNum,      // Returns file reference number

         SInt8          permission)     // Requested permission level

The fileSpec parameter points to a file-system specification record (described in Listing 6 ) telling which movie file to open. The OpenMovieFile function returns a file reference number, via the resRefNum parameter, that uniquely identifies this movie file. You'll use this reference number to refer to the file when calling other QuickTime routines, such as CloseMovieFile and NewMovieFromFile . The permission parameter specifies the level of access permission requested for the file, such as fsRdPerm (read-only), fsWrPerm (write-only), or fsRdWrPerm (read-write).

After opening the movie file, you can read the movie's contents into a movie record, an opaque data structure in which QuickTime reads some information into memory about the movie's contents. The movie record is referred to by a movie identifier of type Movie :



 
typedef  MovieRecord*  Movie;

The QuickTime function NewMovieFromFile creates movie record in memory for the specified file:



 
OSErr

    NewMovieFromFile

        (Movie      *theMovie,          // Returns movie identifier

         short       resRefNum,         // File reference number

         short      *resID,             // Unused in Windows; set to nil

         StringPtr   resName,           // Unused in Windows; set to nil

         short       newMovieFlags,     // Option flags

         Boolean    *dataRefWasChanged) // Unused in Windows; set to nil

You identify the movie file by supplying the file reference number (resRefNum ) that you got back from your call to OpenMovieFile . Parameter theMovie returns a movie identifier for the movie retrieved from the file. Of the possible option flags that you can set in the newMovieFlags parameter, the only one of interest on the Windows platform is newMovieActive , which controls whether the movie will initially be active or inactive when you read it in; you can later control this setting dynamically with the QuickTime function SetMovieActive . The remaining parameters refer to Macintosh-style resources, and are not relevant in the Windows context.

Once you've read a movie in from its file to a movie record and obtained a movie identifier for it, there's no need to keep the movie file open any longer. In the movie record, there are pointers to the file and QuickTime will automatically reopen it to retrieve data, if needed. It's considered good practice to close the file immediately, using the QuickTime function CloseMovieFile :



 
OSErr 

    CloseMovieFile 

        (short  resRefNum)                      // File reference number

Once again, you identify the file by using the file reference number you received when you first opened it. After closing the file, the file reference number is invalid. Therefore, passing the reference to another file manager call is not a good idea and should be avoided.

Listing 8 illustrates how to combine these QuickTime calls to read a movie in from its movie file.

Listing 8 Reading a movie from a file



 
FSSpec   fileSpec;                          // Descriptive information on file to open

short    theFile;                           // Reference number of movie file

Movie    theMovie;                          // Movie identifier

HWND     hWnd;                              // Handle to window

OSErr    errCode;                           // Result code

        ·

        ·

errCode = OpenMovieFile (&fileSpec, &theFile, fsRdPerm);    // Open the movie file

if ( errCode != noErr )                                     // Was there an error?

    {   

        MessageBox (hWnd, "Error opening movie file",       // Notify user

                        "", MB_OK);

        return (FALSE);                                     // Report failure

                

    }  /* end if ( errCode != noErr ) */





errCode = NewMovieFromFile (&theMovie, theFile,             // Get movie from file

                            nil, nil,

                            newMovieActive, nil);

CloseMovieFile (theFile);                                   // Close the file



if ( errCode != noErr)                                      // Was there an error?

    {   

        MessageBox (hWnd, "Error reading movie from file",  // Notify user

                        "", MB_OK);

        return (FALSE);                                     // Report failure

                

    }  /* end if ( errCode != noErr ) */